TOTAL
The TOTAL function returns the sum of the elements of Array. The sum of the array elements over a given dimension is returned if the Dimension argument is present.
Examples
See Additional Examples for more information on using TOTAL.
This example sums the elements of a one-dimensional array:
; Define a one-dimensional array:
A = [20, 10, 5, 5, 3]
; Sum the elements of the array:
SUMA = TOTAL([20, 10, 5, 5, 3])
; Print the results:
PRINT, 'A = ', A
PRINT, 'Sum of A = ', SUMA
IDL prints:
A = 20 10 5 5 3
Sum of A = 43.0000
Syntax
Result = TOTAL( Array [, Dimension] [, /CUMULATIVE] [, /DOUBLE] [, /INTEGER] [, /NAN] [, /PRESERVE_TYPE] )
Return Value
Returns the array sum for the specified dimensions.
Arguments
Array
The array to be summed. This array can be of any basic type except string. If Array is double-precision floating-point, complex, or double-precision complex, the result is of the same type. Otherwise, the result is single-precision floating-point.
Dimension
An optional argument specifying the dimension over which to sum, starting at one. If this argument is not present or zero, the scalar sum of all the array elements is returned. If this argument is present, the result is an array with one less dimension than Array. For example, if the dimensions of Array are N1, N2, N3, and Dimension is set to 2, the dimensions of the result are (N1, N3), and element [i,j] of the result contains the sum:
Keywords
CUMULATIVE
If this keyword is set, the result is an array of the same size as the input, with each element, i, containing the sum of the input array elements 0 to i. This keyword also works with the Dimension parameter, in which case the sum is performed over the given dimension. Note that if the input only has a single element, then a scalar is returned.
Tip: If the input array is a temporary variable or an expression, and the result type matches the input type (for example by using the PRESERVE_TYPE keyword), then TOTAL will perform the cumulative sum in place and no additional memory will be used.
DOUBLE
Set this keyword to force the summation to be done using double-precision arithmetic. By default, if the input is of type DOUBLE, DCOMPLEX, LONG64, or ULONG64, IDL does the summation using double precision; otherwise IDL does the summation using single precision. If this keyword is set to zero, IDL still does the summation using the default precision, but the result is converted to single precision before returning.
INTEGER
Set this keyword to perform the TOTAL using integer arithmetic, and to return an integer result. If Array is of type ULONG64 then unsigned 64-bit integers are used for the computation and the Result is of type ULONG64, otherwise signed 64-bit integers are used and the Result is of type LONG64. If Array is complex and INTEGER is set, then only the real part of each value is used for the computation. The DOUBLE keyword is ignored if INTEGER is set.
Note: If Array has a large number of values or the values themselves are large, then the TOTAL with the INTEGER keyword may easily overflow the largest 64-bit integer and return an incorrect result. In this case you may want to avoid using the INTEGER keyword.
NAN
Set this keyword to cause the routine to check for occurrences of the IEEE floating-point values NaN or Infinity in the input data. Elements with the value NaN or Infinity are treated as missing data.
Note: Since the value NaN is treated as missing data, if Array contains only NaN values the TOTAL routine will return 0.
PRESERVE_TYPE
Set this keyword to perform the TOTAL using the input type, and to return a result of the same type. The DOUBLE and INTEGER keywords are ignored if PRESERVE_TYPE is set.
Note: For byte or integer data the TOTAL with PRESERVE_TYPE may easily overflow the largest value for that type. The PRESERVE_TYPE keyword is only useful if you know that your values will not overflow, or you want to exploit the overflow, for example in computing a checksum. Otherwise, you may want to use the INTEGER keyword instead.
Thread Pool Keywords
This routine is written to make use of IDL’s thread pool, which can increase execution speed on systems with multiple CPUs. The values stored in the !CPU system variable control whether IDL uses the thread pool for a given computation. In addition, you can use the thread pool keywords TPOOL_MAX_ELTS, TPOOL_MIN_ELTS, and TPOOL_NOTHREAD to override the defaults established by !CPU for a single invocation of this routine. See Thread Pool Keywords for details.
The thread pool is used for non-cumulative sums, and is not used if the CUMULATIVE keyword is specified. In a cumulative sum, each result value depends on all of the previous results, so overlapped execution is not possible.
When summing a large number of values, the result from TOTAL can depend heavily upon the order in which the numbers are added. Since the thread pool will add values in a different order, you may obtain a different — but equally correct — result than that obtained using the standard non-threaded implementation. This effect occurs because TOTAL uses floating point arithmetic, and the mantissa of a floating point value has a fixed number of significant digits. The effect is especially obvious when using single precision arithmetic, but can also affect double precision computations. Such differences do not mean that the sums are incorrect. Rather, they mean that they are equal within the ability of the floating point representation used to represent them. For more information on floating-point numbers, see Accuracy and Floating Point Operations.
It is also worth noting that this effect, while illustrated by the use of the thread pool, is not caused by the use of threading. It is caused by the different order in which the numbers are summed, as can be illustrated by the following non-threaded example:
vec = FINDGEN(100000)
PRINT, TOTAL(vec, /TPOOL_NO) - TOTAL(REVERSE(vec), /TPOOL_NO)
IDL prints:
-96768.0
As you can see, the small floating-point errors can accumulate across the sum of a large number of values.
The computation above was done on a Sun Sparc workstation. Your result will depend on the architecture of your CPU; it may be slightly different, and in the notable case of Intel-compatible X86 CPUs may actually be zero due to the use of internal 80-bit floating point registers on that CPU which give it better than double precision accuracy for some computations. The order of operations can influence the result.
Additional Examples
The results are different when a multi-dimensional array is used:
; Define a multi-dimensional array:
A = FINDGEN(5,5)
; Sum each of the rows in A:
SUMROWS = TOTAL(A, 1)
; Sum each of the columns in A:
SUMCOLS = TOTAL(A, 2)
; Print the results:
PRINT, 'A = ', A
PRINT, 'Sum of each row:', SUMROWS
PRINT, 'Sum of each column:', SUMCOLS
IDL prints:
A = 0.000000 1.00000 2.00000 3.00000 4.00000
5.00000 6.00000 7.00000 8.00000 9.00000
10.0000 11.0000 12.0000 13.0000 14.0000
15.0000 16.0000 17.0000 18.0000 19.0000
20.0000 21.0000 22.0000 23.0000 24.0000
Sum of each row: 10.0000 35.0000 60.0000 85.0000 110.000
Sum of each column: 50.0000 55.0000 60.0000 65.0000 70.0000
Version History
|
Original |
Introduced |
|
6.1 |
Added INTEGER and PRESERVE_TYPE keywords |